home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / batchut / magic.zip / MAGIC.DOC next >
Text File  |  1987-08-23  |  11KB  |  265 lines
  1. 
  2.  
  3.           magic          magic          magic                  DNS C Documentation               Page -1-
  4.  
  5.  
  6.           NAME          NAME          NAME
  7.  
  8.           magic special-characters-to-output
  9.           magic -get arguments
  10.           magic -detab[n] [infile [outfile]]
  11.  
  12.           DESCRIPTION          DESCRIPTION          DESCRIPTION
  13.  
  14.           magic          magic          magic  is a multipurpose utility for the IBM PC & compatibles. It
  15.           allows you to easily output "special"  character  stings  to  the
  16.           screen  (like  escape sequences), provides interactive batch file
  17.           input, and can detab (expand tabs  into  whitespace)  in  a  text
  18.           file.
  19.  
  20.           __________ _______ __________          Outputting Special Characters
  21.  
  22.                    magic                   magic          Program  magic  can be used to generate character sequences which
  23.                                                 magic                                                magic          are normally hard to generate. Typing magic alone  shows  how  to
  24.           use  the program. The following special symbols are recognized by
  25.           magic          magic          magic. The curly braces are required.
  26.  
  27.                {ESC}           Writes the ESC character
  28.                {CR}            Writes a CRLF (Enter)
  29.                {TAB}           Writes a TAB
  30.                {FF}            Writes a form feed
  31.                {0xnn}          Writes hex number nn
  32.                ^S              Writes Ctrl-S
  33.  
  34.                     ___          Note that any character can be written with the {0xnn} mechanism,
  35.           and that a ^ (hat) immediately preceding a character  writes  the
  36.           control of that character.
  37.  
  38.           Our AUTOEXEC.BAT's have the following lines of code in them:
  39.  
  40.                magic {cr} | print /B:4096  > null
  41.                magic {ff} > lpt1
  42.                magic {esc}[2J{esc}[34;46m
  43.  
  44.                                                                    magic                                                                   magic          The  first example installs the DOS PRINT command, where magic is
  45.           used to write an Enter, which is piped into PRINT to  answer  the
  46.           question PRINT asks you.
  47.  
  48.           The  second example sends a form feed to our printer, ensuring it
  49.           is starting out on a fresh, unbent page.
  50.  
  51.           The third example shows how we can write some  ESC  sequences  to
  52.           the screen to clear the screen and set our screen colors.
  53.  
  54.           _ _____ ____ ________          A Batch File Enhancer
  55.  
  56.           magic          magic          magic  can  be  invoked  to  get responses from the user, and set
  57.           error return codes to indicate how the user responded.  Usage  is
  58.           as follows:
  59.  
  60.                magic -get arguments
  61.  
  62.  
  63.  
  64.                                                                       magic                                                                      magic                                   August 23, 1987                    magic
  65.  
  66.  
  67.  
  68.  
  69.           magic          magic          magic                  DNS C Documentation               Page -2-
  70.  
  71.  
  72.           Arguments are as follows:
  73.  
  74.                -beep
  75.                -prompt "Query for user"
  76.                -default=response
  77.                -timeout=nn
  78.                resp=errnum
  79.  
  80.                -beep                             magic               -beep                             magic          The  -beep  option beeps the user when magic is run, to encourage
  81.           the user to look at his screen.
  82.  
  83.               -default         -df              -default         -df          The -default option (-df for short) allows you  to  specify  what
  84.           the default response should be (if the user just hits Enter).
  85.  
  86.                -timeout           -to               -timeout           -to          The  -timeout  option  (-to  for  short)  allows you to specify a
  87.           number of seconds after which the default answer will be supplied
  88.                              ____          automatically. You must  supply  a  default  if  you  expect  the
  89.           timeout to work.
  90.  
  91.           resp                                                       errnum          resp                                                       errnum          resp  is  text which the user is expected to respond with. errnum
  92.           is a number, 0-255, which will be returned as an error code.  The
  93.           error code can be checked in a batch file easily.
  94.  
  95.           Here is a real example of usage:
  96.  
  97.                magic -get abc=1 def=2 ghi=3
  98.  
  99.           will  return  an  error  of 1 if the user types in abc, a 2 if he
  100.           types in def, etc. When typing  in  the  relationship  between  a
  101.           string and an error code, there can be no spaces.
  102.  
  103.           Here are some more complicated examples:
  104.  
  105.                magic -get -prompt "Format (y/n)? " -default=y  y=1 n=2
  106.                magic -get -default=abc -timeout=20 abc=1 def=2 ghi=3
  107.  
  108.                                   magic                                  magic          In  the  first example, magic detects that all possible responses
  109.           are a single character, and will not  require  the  user  to  hit
  110.           Enter (i.e. just hitting Y or N is enough).
  111.  
  112.                              -prompt         -pr                             -prompt         -pr          If  you  use  the  -prompt option (-pr for short), the next thing
  113.           following the -prompt is taken  to  be  the  prompt  to  display.
  114.           Surrounding the prompt string with quotes (as shown above) allows
  115.           you to have a multi word prompt.
  116.  
  117.                                              magic                                             magic          Here is a BAT file which shows how magic is used in real life:
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.                                                                       magic                                                                      magic                                   August 23, 1987                    magic
  131.  
  132.  
  133.  
  134.  
  135.           magic          magic          magic                  DNS C Documentation               Page -3-
  136.  
  137.  
  138.                echo off
  139.                echo Enter either abc, def, or ghi
  140.                magic -get -default=abc abc=1 def=2 ghi=3
  141.                rem = Errorlevel checks in reverse numeric order =
  142.                if errorlevel 3 goto three
  143.                if errorlevel 2 goto two
  144.                if errorlevel 1 goto one
  145.                goto quit
  146.                rem Action if user types abc
  147.                :one
  148.                echo one
  149.                goto quit
  150.                rem Action if user types def
  151.                :two
  152.                echo two
  153.                goto quit
  154.                rem Action if user types ghi
  155.                :three
  156.                echo three
  157.                goto quit
  158.                :quit
  159.  
  160.           Note that the error level checks are in decreasing numeric order.
  161.           This  is  required  due to the nature of the way DOS performs the
  162.           tests.
  163.  
  164.           ____ ________          File Detabber
  165.  
  166.                       magic                      magic          You can use magic to  remove  (expand)  tabs  from  a  file.  The
  167.           default tab expansion is 4 spaces. This default can be overridden
  168.           by setting an environment variable called TAB to your desired tab
  169.           expansion. You can also tack a number on to the end of the -detab
  170.           option on the command line, e.g.
  171.  
  172.                magic -detab3
  173.  
  174.           The  number  following  the  -detab  overrides  both  the program
  175.                   ___          default and your (optional) TAB environment variable.
  176.  
  177.           With no other command line arguments, input is expected  to  come
  178.           from  standard  input,  and  the  detabbed  output will go to the
  179.                                                          magic